Developer Documentation

QuickTime 4 API Documentation

QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top | Next |

Enhancing Movie Playback Performance

There are four new functions you can use to enhance movie playback.

SetTrackLoadSettings

The SetTrackLoadSettings function allows you to specify a portion of a track that is to be loaded into memory whenever it is played.

pascal void SetTrackLoadSettings (
                     Track theTrack,
                     TimeValue preloadTime,
                     TimeValue preloadDuration,
                     long preloadFlags,
                     long defaultHints);
theTrack
Specifies the track for this operation. Your application obtains this track identifier from such toolbox functions as NewMovieTrack and GetMovieTrack .

preloadTime
Specifies the starting point of the portion of the track to be preloaded. Set this parameter to -1 if you want to preload the entire track (in this case the function ignores the preloadDuration parameter). This parameter should be specified using the movie's time scale.

preloadDuration
Specifies the amount of the track to be preloaded, starting from the time specified in the preloadTime parameter. If you are preloading the entire track, the function ignores this parameter.

preloadFlags
Controls when the toolbox preloads the track. The function supports the following flag values:

preloadAlways
Specifies that the toolbox should always preload this track, even if the track is disabled.

preloadOnlyIfEnabled
Specifies that the toolbox should preload this track only when the track is enabled.

Set this parameter to 0 if you do not want to preload the track.

defaultHints
Specifies playback hints for the track. You may specify any of the supported hints flags. See "Hints" for descriptions of new hint flags in QuickTime.

Description

The SetTrackLoadSettings allows you to control how the toolbox preloads the tracks in your movie. By using these settings, you make this information part of the movie, so that the preloading takes place every time the movie is opened, without an application having to call the LoadTrackIntoRAM function. Consequently, you should use this feature carefully, so that your movies do not consume large amounts of memory when opened.

Special Considerations

The toolbox transfers this preload information when you call the CopyTrackSettings function. In addition, the preload information is preserved when you save or flatten a movie (using either the FlattenMovie or FlattenMovieData functions). In flattened movies, the tracks that are to be preloaded are stored at the start of the movie, rather than being interleaved with the rest of the movie data. This improves preload performance.

RESULT CODES

invalidTrack
-2009 This track is corrupted or invalid

GetTrackLoadSettings

The GetTrackLoadSettings function allows you to retrieve a track's preload information.

pascal void GetTrackLoadSettings (
                     Track theTrack,
                     TimeValue *preloadTime,
                     TimeValue *preloadDuration,
                     long *preloadFlags,
                     long *defaultHints);
theTrack
Specifies the track for this operation. Your application obtains this track identifier from such toolbox functions as NewMovieTrack and GetMovieTrack .

preloadTime
Specifies a field to receive the starting point of the portion of the track to be preloaded. The toolbox returns a value of -1 if the entire track is to be preloaded.

preloadDuration
Specifies a field to receive the amount of the track to be preloaded, starting from the time specified in the preloadTime parameter. If the entire track is to be preloaded, this value is ignored.

preloadFlags
Specifies a field to receive the flags that control when the toolbox preloads the track. The function supports the following flag values:

preloadAlways
Specifies that the toolbox always preloads this track.

preloadOnlyIfEnabled
Specifies that the toolbox preloads this track only when the track is enabled.

defaultHints
Specifies a field to receive the playback hints for the track.

RESULT CODES

invalidTrack
-2009 This track is corrupted or invalid

GetTrackDisplayMatrix

The GetTrackDisplayMatrix function returns a matrix that is the concatenation of all matrices currently effecting the track's location, scaling, and so on. This includes the movie's matrix, the track's matrix, and the modifier matrix. Since modifier information is passed between tracks at MoviesTask time, the information returned by this call represents the matrix in effect at the last MoviesTask call.

pascal OSErr GetTrackDisplayMatrix(
                     Track theTrack,
                     MatrixRecord *matrix );
theTrack
Specifies the track for this operation. Your application obtains this track identifier from such toolbox functions as NewMovieTrack and GetMovieTrack .

matrix
Contains a pointer to a matrix structure.

Note
To determine the entire clip of a track at the current time using GetTrackDisplayBoundsRgn . The results of GetTrackDisplayBoundsRgn take into account any clip regions provided by modifier tracks.

RESULT CODES

invalidTrack
-2009 This track is corrupted or invalid

PrePrerollMovie

Sets up any necessary network connections to receive streaming content. Beginning with QuickTime 4, your application should call PrePrerollMovie any time it calls PrerollMovie.

OSErr PrePrerollMovie(
       Movie m
       TimeValue time
       Fixed rate
       MoviePrePrerollCompleteUPP proc
       void *refcon );

m
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

time
Contains the starting time of the movie segment to play.

rate
Specifies the rate at which you anticipate playing the movie. You specify the movie rate as a 32-bit, fixed-point number. Positive integers indicate forward rates and negative integers indicate reverse rates.

proc
The completion proc you want called when pre-prerolling is complete. PrePrerollMovie operates asynchronously if a completion proc is specified, or synchronously if none is specified.

refcon
A reference constant. Use this parameter to point to a data structure containing any information your application needs.

DISCUSSION

Before a movie is played, it is normally prerolled. During preroll, the Movie Toolbox tells the appropriate media handlers to load the movie data, allocate sound channels, start up image-decompression sequences, and so on.

Before a movie that contains streaming content is prerolled, it must be pre-prerolled. This sets up any necessary network connections between the client and the server.

If a movie contains streaming content (one or more 'strm' tracks), you must call PrePrerollMovie before calling PrerollMovie. If the movie does not contain streaming content, calling PrePrerollMovie has no effect. If your application calls the PrerollMovie function, it should always call the PrePrerollMovie function first.

If you play movies using a movie controller, you do not need to preroll or pre-preroll the movie explicitly; it is done for you automatically.

If a completion proc is specified in the MoviePrePrerollCompleteUPP parameter, PrePrerollMovie is asynchronous; it returns almost immediately and calls the completion proc when pre-prerolling is complete. If no completion proc is specified, PrePrerollMovie operates synchronously and the function will not return until pre-prerolling is complete. This can take a long time, particularly if a dial-up network connection must be established.

RESULT CODES

invalidMovie -2010 This movie is corrupted or invalid
invalidTime -2015 This time value is invalid
network errors   
© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |